home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1998 November / Freeware November 1998.img / dist / fw_gnuplot.idb / usr / freeware / doc / gnuplot / README.z / README
Text File  |  1998-05-21  |  9KB  |  246 lines
  1. Notes on the gnuplot help files and documentation.
  2. --------------------------------------------------
  3.  
  4. Gnuplot documentation is available in three ways:
  5.  
  6. 1 - interactively, within gnuplot
  7. 2 - as a printed document. 
  8. 3 - as a manual page, through the Unix man(1) facility
  9.  
  10. The third form tells how to run gnuplot.
  11.  
  12. The first two forms describe the inner workings, and contain equivalent
  13. information.  They derive their information from the file "gnuplot.doc",
  14. which is the master copy of gnuplot help information.  All other forms,
  15. except for the man page "gnuplot.1", are derived from it. 
  16.  
  17. gnuplot.doc -> gnuplot.gih 
  18.             -> gnuplot.hlp
  19.             -> gnuplot.html
  20.             -> gnuplot.info
  21.             -> gnuplot.itl
  22.             -> gnuplot.ms
  23.             -> gnuplot.rtf
  24.             -> gnuplot.tex
  25.                                       
  26. On Unix, AmigaDOS, and MSDOS the interactive help is built into the
  27. program, and uses the file "gnuplot.gih" ('make gih').
  28.  
  29. On VMS, the interactive help is supplied by the system help facility,
  30. using the file "gnuplot.hlp".  This is made with 'make hlp' and must
  31. be put into a library, either a specific "gnuplot.hlb" or any of the
  32. system-wide help libraries, using lib/help ('help lib').  If VMS users
  33. prefer the gnuplot interactive help facility to the system facility,
  34. this can be easily changed in "command.c".
  35.  
  36. On the World Wide Web, the gnuplot manual can include demonstration
  37. plots; the links for these are included in the file "gnuplot.html"
  38. ('make html').
  39.  
  40. Under EMACS, interactive help uses the file "gnuplot.info" ('make info').
  41.  
  42. On OS/2, the interactive help uses the file "gnuplot.itl".
  43.  
  44. The printed document is available in troff/nroff (ms) format, using
  45. the file "gnuplot.ms".  For nroff, use 'make nroff'. For troff, type
  46. 'make ms' and then 'troff -ms gnuplot.ms' in whatever way you use troff.
  47. For groff (on linux), use  'groff -t -e -mgs gnuplot.ms'
  48.  
  49. On MS-Windows, the Microsoft help compiler converts the file "gnuplot.rtf"
  50. to an 'hlp' file which is used by the standard Windows help program.
  51.  
  52. The printed document is also available in LaTeX format, using the file
  53. "gnuplot.tex" ('make tex').  If you use LaTeX on your computer, you can
  54. type 'make dvi' to create "gnuplot.dvi", and then run your dvi-to-
  55. PostScript converter to generate "gnuplot.ps".
  56.  
  57.  
  58. Manual entries for the terminals are not included in "gnuplot.doc";
  59. instead, each "driver.trm" file (in the directory /term) contains its
  60. own documentation section.
  61.  
  62. When you build gnuplot, only some of the terminal drivers are loaded;
  63. these are selected in "term.h" by compiler directives specified in the
  64. makefile.  The interactive help generators use the same set of compiler
  65. directives in "term.h", and thus interactive help contains information
  66. for just those terminals actually loaded.
  67.  
  68. The printed manual generators and the html generator contain information
  69. about all terminals.  This is accomplished by concatenating all of the
  70. ".trm" files into a single one, "allterm.h".
  71.  
  72. The routine "termdoc.c" is #included by each of the eight processing
  73. programs ("doc2gih.c", etc.); it in turn #includes either "term.h" or
  74. "allterm.h", as is appropriate.  If you wish to override the default
  75. decision about which terminals are to appear in the documentation, edit
  76. the appropriate "doc2" program to either #define or #undefine ALL_TERM.
  77.  
  78.  
  79. Description of the gnuplot.doc format:
  80. --------------------------------------
  81.  
  82. Here is an example of the DOC master help format:
  83.  
  84. ?
  85. 1 gnuplot
  86.  GNUPLOT is a command-driven interactive function plotting program.  It
  87.  ...
  88. ?exit
  89. 2 exit
  90.  'exit', 'quit' and ...
  91. ?expressions
  92. 2 expressions
  93.  In general, any mathematical expression accepted by C, ...
  94.  
  95.  Topics:
  96.  functions operators
  97. ?expressions functions
  98. ?functions
  99. 3 functions
  100.  The functions in GNUPLOT are ...
  101.  
  102.  Topics:
  103.  abs acos arg ...
  104. ?expressions functions abs
  105. ?functions abs
  106. ?abs
  107. 4 abs
  108.  This function returns the absolute value of its argument.  The
  109.  returned value is of the same type as the argument. 
  110. ?expressions functions acos
  111. ?functions acos
  112. ?acos
  113. 4 acos
  114.  This function returns the arc cosine (inverse cosine) of its
  115.  argument.  'acos' returns its argument in radians. 
  116.  
  117.  
  118. Some notes about the format:
  119. ----------------------------
  120. Remember that all text must be able to be processed by gnuplot, VMS,
  121.  nroff, troff, info, itl, and latex, and always do something reasonable. 
  122. The first column is reserved for control characters.
  123. Text does not start in the first column.
  124. Lines that start in column 2 may be typeset by LaTeX.
  125. Lines that have a space in column 2 are to be printed in a verbatim
  126.  environment by LaTeX.
  127. Tables must have a space in column 2.
  128. Do NOT use tabs in the help file.
  129. Conversion from this format to vax .hlp file involves removal of
  130.  lines starting with [?@#$%] (see doc2hlp). VMS uses the numbers
  131.  to represent a tree. 
  132. Conversion from this format to gnuplot .gih file involves removal of
  133.  lines starting with [0-9@#$%] (see doc2gih). Gnuplot matches your
  134.  help query against the ? lines to find the help information.
  135.  Multiple ? lines for one text block constitute synonyms. The most
  136.  specific should be first, eg 'expressions functions' before 'functions'.
  137.  Spaces are allowed here, but should be single.
  138. Backquote pairs are converted by the doc2tex program into boldface;
  139.  that is, `some text` is converted to {\bf some text}. Be sure to pair
  140.  the backquotes, or the whole document will be boldface! doc2ms converts
  141.  `` pairs to \fB...\fR, except inside tables : for the moment, this
  142.  has to be done manually on the lines starting %, but we ought to
  143.  find some way to allow tables to be entered just the once !
  144.  
  145. Control characters in first column:
  146. ?    used by .gih format, for builtin interactive help - keyword
  147. 0-9  used by VMS help and by doc2{tex,ms} formatters to define level,keyword
  148. @    used by doc2{tex,ms} to define table start/end
  149. #    used by doc2tex: table entry
  150. %    used by doc2ms: table entry
  151. ^    used by doc2html : hypertext link
  152. <    the help from the terminal driver files is inserted at this point.
  153. C    comment (mainly for RCS ID line)
  154. C#   reserved form of comment (used internally by termdoc.c)
  155.  
  156.  
  157.  
  158. Rules for stylistic consistency (courtesy Jens Emmerich):
  159.  
  160. 0. General
  161.  
  162.    * Use your brain -- the reader has one, too (at least in theory).
  163.  
  164.    * Format according to the logical structure, not according to
  165.      visual charm.
  166.  
  167.    * Keep things short.  Don't split lines without a good reason.  Many
  168.      people still use 24 line terminals/screens.  Backslashify lines
  169.      only in code examples.
  170.  
  171.  
  172. 1. Verbatim lines: start column and line length 
  173.  
  174.    * Verbatim text starts in column 8 (7 spaces before the text).  The
  175.      reason is that "Syntax:" is 7 and "Examples:" is 9 characters
  176.      wide.  Adding the space in column 1 we have 1 resp. 3 characters
  177.      "overlap" in the online text versions, which is still easy to
  178.      read as all commands are at least 3 characters long.  This does
  179.      not apply to the "interactive clear text form"-tables.
  180.  
  181.    * The rightmost used column is column 73 (counting from 1).  This
  182.      allows LaTeX formatted documents with only slightly wider text
  183.      than default, which adds to readability.
  184.  
  185. 2. Line spacing
  186.  
  187.    * An empty line goes before "Syntax:" and "Example:", but not after
  188.      them.  Without these keywords, add an empty line before verbatim
  189.      lines if they are not embedded in a sentence.
  190.  
  191.    * Leave blank lines within verbatim environments only if it is
  192.      really needed for clarity.
  193.  
  194.    * Verbatim environments are separated from the following text by a
  195.      blank line, but not if they are embedded in a sentence.
  196.  
  197.    * Short explanations within examples can be embedded within
  198.      comments if they are really short, otherwise use "normal" text
  199.      (beginning at column 2) and leave no blank lines between the text
  200.      and the example.
  201.  
  202. 3. Spaces around braces 
  203.  
  204.    * In general don't put a space after an opening "{" or before a
  205.      closing brace "}".  This makes everything wider and harder to
  206.      spot.
  207.  
  208.    * Do insert a space in the following situations:
  209.      
  210.      - where it adds clarity to nesting levels >=3 of braces; usually
  211.        only one brace for the outermost brace on a particular line 
  212.        (see 'set grid')
  213.      
  214.      - on multiple line optional constructs (see 'set xtics')
  215.  
  216.    * Separate multiple optional constructs by a space.
  217.  
  218.    * Don't separate them if they belong together. (see 'set title')
  219.  
  220.    * Do separate them if they belong together but require a space in
  221.      between (see 'set ticscale').
  222.  
  223.    * Part of these rules are really a consequence of gnuplot's
  224.      inconsistent syntax.
  225.  
  226. 4. Placing and spaces around "|"
  227.  
  228.    * Place a space before and after the "|".  Otherwise the
  229.      alternatives tend to optically 'melt' and they are harder to
  230.      read. 
  231.  
  232.    * Keep or-expressions on one line, if possible.
  233.  
  234.    * On multi-line expressions place the "|" at the beginning of the
  235.      next line rather than the end of the first.  This makes it easier
  236.      to see that the expression continues.  Align the first components;
  237.      this requires indenting the first line a bit further (see 'set
  238.      cntrparam').
  239.  
  240. 5. Comma-separated optional argument lists
  241.  
  242.    * Place the space before the opening brace rather within the braces
  243.      after the comma (as one normally does) (see 'set isosamples').
  244.  
  245.  
  246.